home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / menubar.n < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. tk_menuBar(n)              Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      tk_menuBar, tk_bindForTraversal - Support for menu bars
  12.  
  13. SYNOPSIS
  14.      tk_menuBar _f_r_a_m_e ?_m_e_n_u _m_e_n_u ...?
  15.  
  16.      tk_bindForTraversal _a_r_g _a_r_g ...
  17. _________________________________________________________________
  18.  
  19.  
  20. DESCRIPTION
  21.      These two commands are  Tcl  procedures  in  the  Tk  script
  22.      library.  They provide support for menu bars.  A menu bar is
  23.      a frame that contains a collection of menu buttons that work
  24.      together, so that the user can scan from one menu to another
  25.      with the mouse: if the mouse  button  is  pressed  over  one
  26.      menubutton  (causing  it  to post its menu) and the mouse is
  27.      moved over another menubutton in the same menu  bar  without
  28.      releasing the mouse button, then the menu of the first menu-
  29.      button is unposted and the menu of  the  new  menubutton  is
  30.      posted  instead.   Menus  in a menu bar can also be accessed
  31.      using keyboard traversal (i.e.  by typing keystrokes instead
  32.      of  using  the  mouse).   In order for an application to use
  33.      these  procedures,  it  must  do  three  things,  which  are
  34.      described in the paragraphs below.
  35.  
  36.      First, each application  must  call  tk_menuBar  to  provide
  37.      information about the menubar.  The _f_r_a_m_e argument gives the
  38.      path name of the frame that contains all of  the  menu  but-
  39.      tons,  and the _m_e_n_u arguments give path names for all of the
  40.      menu buttons associated with the menu bar.   Normally  _f_r_a_m_e
  41.      is  the  parent of each of the _m_e_n_u's.  This need not be the
  42.      case, but _f_r_a_m_e must be an ancestor of each of the _m_e_n_u's in
  43.      order  for grabs to work correctly when the mouse is used to
  44.      pull down menus.  The order of the _m_e_n_u arguments determines
  45.      the  traversal order for the menu buttons.  If tk_menuBar is
  46.      called without any _m_e_n_u arguments, it returns  a  list  con-
  47.      taining  the  current  menu  buttons  for _f_r_a_m_e, or an empty
  48.      string if _f_r_a_m_e isn't currently set up as a  menu  bar.   If
  49.      tk_menuBar  is called with a single _m_e_n_u argument consisting
  50.      of an empty string, any menubar  information  for  _f_r_a_m_e  is
  51.      removed;   from  now  on  the  menu  buttons  will  function
  52.      independently without keyboard traversal.  Only one menu bar
  53.      may be defined at a time within each top-level window.
  54.  
  55.      The second thing an application must do is to  identify  the
  56.      traversal  characters  for  menu  buttons  and menu entries.
  57.      This is done  by  underlining  those  characters  using  the
  58.      -underline options for the widgets.  The menu traversal sys-
  59.      tem uses  this  information  to  traverse  the  menus  under
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. tk_menuBar(n)              Tk Commands
  71.  
  72.  
  73.  
  74.      keyboard control (see below).
  75.  
  76.      The third thing that an application must do is to make  sure
  77.      that  the  input  focus  is always in a window that has been
  78.      configured to support menu traversal.  If the input focus is
  79.      none  then  input  characters  will be discarded and no menu
  80.      traversal will be possible.  If you have no other  place  to  |
  81.      set  the  focus,  set  it to the menubar widget:  tk_menuBar  |
  82.      creates bindings for its  _f_r_a_m_e  argument  to  support  menu  |
  83.      traversal.                                                    |
  84.  
  85.      The Tk startup scripts configure all the Tk  widget  classes  |
  86.      with  bindings  to support menu traversal, so menu traversal  |
  87.      will be possible regardless of which widget has  the  focus.
  88.      If your application defines new classes of widgets that sup-
  89.      port   the   input   focus,    then    you    should    call
  90.      tk_bindForTraversal    for    each    of    these   classes.
  91.      Tk_bindForTraversal takes any number of arguments,  each  of
  92.      which  is  a widget path name or widget class name.  It sets
  93.      up bindings for all the named widgets and  classes  so  that
  94.      the  menu  traversal system will be invoked when appropriate
  95.      keystrokes are typed in those widgets or classes.
  96.  
  97.  
  98. MENU TRAVERSAL BINDINGS
  99.      Once  an  application  has  made  the   three   arrangements
  100.      described  above,  menu traversal will be available.  At any
  101.      given time, the only menus available for traversal are those
  102.      associated  with  the  top-level window containing the input
  103.      focus.  Menu traversal is initiated by one of the  following
  104.      actions:
  105.  
  106.      [1]  If <F10> is typed, then the first menu  button  in  the
  107.           list  for  the top-level window is posted and the first
  108.           entry within that menu is selected.
  109.  
  110.      [2]  If <Alt-_k_e_y> is pressed, then the menu button that  has
  111.           _k_e_y as its underlined character is posted and the first
  112.           entry within that menu  is  selected.   The  comparison
  113.           between  _k_e_y and the underlined characters ignores case
  114.           differences.  If no menu button matches  _k_e_y  then  the
  115.           keystroke has no effect.
  116.  
  117.      [3]  Clicking mouse button 1 on a  menu  button  posts  that
  118.           menu and selects its first entry.
  119.  
  120.      Once a menu has been posted, the input focus is switched  to
  121.      that menu and the following actions are possible:
  122.  
  123.      [1]  Typing <ESC> or clicking mouse  button  1  outside  the
  124.           menu button or its menu will abort the menu traversal.
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. tk_menuBar(n)              Tk Commands
  137.  
  138.  
  139.  
  140.      [2]  If <Alt-_k_e_y> is pressed, then the entry in  the  posted
  141.           menu  whose  underlined  character  is  _k_e_y is invoked.
  142.           This causes the menu to be unposted, the entry's action
  143.           to  be  taken, and the menu traversal to end.  The com-
  144.           parison between _k_e_y and underlined  characters  ignores
  145.           case  differences.   If  no menu entry matches _k_e_y then
  146.           the keystroke is ignored.
  147.  
  148.      [3]  The arrow keys may be used to move  among  entries  and
  149.           menus.   The  left and right arrow keys move circularly
  150.           among the available menus and the  up  and  down  arrow
  151.           keys  move  circularly among the entries in the current
  152.           menu.
  153.  
  154.      [4]  If <Return> is  pressed,  the  selected  entry  in  the
  155.           posted  menu  is  invoked,  which causes the menu to be
  156.           unposted, the entry's action to be taken, and the  menu
  157.           traversal to end.
  158.  
  159.      When a menu traversal completes, the input focus reverts  to
  160.      the window that contained it when the traversal started.
  161.  
  162.  
  163. KEYWORDS
  164.      keyboard traversal, menu, menu bar, post
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.